<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	  "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>deal.II CMake documentation</title>
    <link href="../screen.css" rel="StyleSheet">
    <meta name="author" content="the deal.II authors <authors @ dealii.org>">
    <meta name="copyright" content="Copyright (C) 2012 - 2019 by the deal.II authors">
    <meta name="keywords" content="deal.II">
  </head>

  <body>


    <h1>Details on the <acronym>deal.II</acronym> configuration and build system</h1>

    <p>
      The <acronym>deal.II</acronym> <a href="../readme.html"
      target="body">README</a> file gives an overview over the basics
      of configuring and building the <acronym>deal.II</acronym>
      library. This page provides more details about using the
      <acronym>deal.II</acronym> CMake build system.
    </p>

    <div class="toc">
      <ol>
	<li><a href="#operating">Operating cmake</a>
          <ol>
            <li><a href="#operatingmanip">Manipulating the cache</a></li>
            <li><a href="#operatingccmake"><code>ccmake</code> and special build targets </a></li>
            <li><a href="#operatingshortcuts">Shortcuts</a></li>
	  </ol>
	</li>
	<li><a href="#build">Configuring and Building deal.II</a>
          <ol>
            <li><a href="#buildtargets">Primary build targets</a></li>
            <li><a href="#buildinformation">Information about current configuration</a></li>
            <li><a href="#buildinsource">Out-of-source versus in-source builds</a></li>
            <li><a href="#buildgenerator">CMake Generators</a></li>
            <li><a href="#buildinstall">Installation</a></li>
	  </ol>
        </li>
	<li><a href="#configure">Configuration options</a>
	  <ol>
	    <li><a href="#configurefeature">Feature configuration</a></li>
	    <li><a href="#configureautoconf">Autoconfiguration</a></li>
	    <li><a href="#configureext">External library locations</a></li>
	    <li><a href="#configureoverride">Manual override</a></li>
	    <li><a href="#configurecomp">Component selection</a></li>
	    <li><a href="#configurebuild">Build configuration</a></li>
	    <li><a href="#compiler">Selecting a compiler</a></li>
	    <li><a href="#configureinstall">Installation</a></li>
	  </ol>
	</li>
	<li><a href="#advanced">Initial cache file and advanced options</a></li>
	<li><a href="#compiling">Compiling only certain parts</a></li>
      </ol>
    </div>

    <a name="operating"></a>
    <h2>Operating cmake</h2>

    <p>
      When configuring <acronym>deal.II</acronym> by
      running <code>cmake</code>, the <code>cmake</code> program
      creates a cache in the current (build) directory that contains
      the values of all (cached) variables that had previously been passed
      as command line arguments, been found through running tests,
      or had otherwise been set.
    </p>

    <p>
      On a subsequent call to <code>cmake</code>, e.g. to change the
      configuration or due to a callback from the build system because some
      configuration file (the <code>CMakeLists.txt</code> and
      <code>cmake/&lt;..&gt;.cmake</code> files) has changed,
      <code>cmake</code> will only run whatever tests are
      necessary; <i>values for variables that are already in the cache
      are not re-evaluated</i>. This means that calling <code>cmake</code>
      a second time without any arguments at all in a situation like this
<pre class="cmake">
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
cmake ../deal.II
</pre>
      has no effect: In particular, the <code>CMAKE_INSTALL_PREFIX</code>
      specified on the first invocation of <code>cmake</code> is
      cached and therefore still valid after the second invocation
      of <code>cmake</code> This is different from the way the
      <code>autoconf/configure</code> mechanism worked.
    </p>

    <p>
      The cache has an important reason: one can modify all sort of
      configuration parameters and thereby interact with the configuration
      system in rather powerful (and, possibly, destructive) ways. For
      example, the following commands
<pre class="cmake">
mkdir build
cd build
cmake  ../deal.II
ccmake
</pre>
      first configure a bare-bone setup and then call
      the <code>ccmake</code> program -- an interactive editor for the
      cached variables. Similarly,
<pre class="cmake">
mkdir build
cd build
cmake  ../deal.II
cmake -D&lt;OPTION&gt;=&lt;VALUE&gt; [...] ../deal.II
</pre>
      sets a variable the second time around without destroying all
      the configuration that has happened the first time around. Likewise,
<pre class="cmake">
mkdir build
cd build
cmake  ../deal.II
cmake -DDEAL_II_WITH_METIS=OFF .
cmake -DDEAL_II_WITH_TRILINOS=ON -DTRILINOS_DIR=/path/to/trilinos .
</pre>
      switches off support for the METIS library that may have been
      automatically detected during the first invocation of
      <code>cmake</code> and enables support for Trilinos by enabling
      <code>DEAL_II_WITH_TRILINOS</code> and setting
      <code>TRILINOS_DIR</code>.
    </p>

    <a name="operatingmanip"></a>
    <h3> Manipulating the cache </h3>

    <p>
      A cached variable can be set on the command line via
<pre class="cmake">
cmake -D&lt;VARIABLE&gt;=&lt;VALUE&gt; .
</pre>

      Cached variables can be removed from the cache via
<pre class="cmake">
cmake -U&lt;VARIABLE&gt; .
</pre>
      It is possible to use <code>-U</code> together with a globbing
      expression. E.g. to remove the current feature configuration and
      rerun the autodetection one can invoke
<pre class="cmake">
cmake -U"DEAL_II_WITH_*" .
</pre>
    </p>

    <a name="operatingccmake"></a>
    <h3> <code>ccmake</code> and special build targets </h3>

    <p>
      A very convenient way to alter the configuration is to use the graphical
      user interface <code>ccmake</code> to the
      variables <code>cmake</code> stores upon running. It can be invoked via
<pre class="cmake">
ccmake .
</pre>
      or by
<pre class="cmake">
make edit_cache
</pre>

      A reconfiguration (without editing the cache) can be run via
<pre class="cmake">
make rebuild_cache
</pre>
    </p>

    <a name="operatingshortcuts"></a>
    <h3> Shortcuts </h3>

    <p>
      All variables starting with <code>WITH_</code> will be automatically
      renamed to <code>DEAL_II_WITH_*</code>. So, it suffices to specify
<pre class="cmake">
cmake -DWITH_MPI=ON &lt;...&gt;
</pre>
      instead of the longer
<pre class="cmake">
cmake -DDEAL_II_WITH_MPI=ON &lt;...&gt;
</pre>
      The same holds for all variables starting with <code>COMPONENT_</code>
      and all individual component names:
      <code>DOCUMENTATION</code>, and <code>EXAMPLES</code>
      (which will be expanded to the full <code>DEAL_II_COMPONENT_*</code>
      variable name).
    </p>



    <a name="build"></a>
    <h2>Configuring and Building deal.II</h2>

    <p>
      This section provides some further details and advanced topics with
      respect to configuration and building that is not covered in the <a
      href="../readme.html" target="body">README</a>.
    </p>

    <a name="buildtargets"></a>
    <h3>Primary build targets</h3>

    <p> The current list of primary build targets can be queried via
    <code>make info</code>:
<pre class="cmake">
###
#
#  The following targets are available (invoke by $ make &lt;target&gt;):
#
#    all            - compile the library and all enabled components
#    clean          - remove all generated files
#    install        - install into CMAKE_INSTALL_PREFIX
#
#    info           - print this help message
#    help           - print a list of valid top level targets
#
#    edit_cache     - run ccmake for changing (cached) configuration variables
#                     and reruns the configure and generate phases of CMake
#    rebuild_cache  - rerun the configure and generate phases of CMake
#
#    compat_files   - build and install component 'compat_files'
#    documentation  - build and install component 'documentation'
#    examples       - build and install component 'examples'
#    library        - build and install component 'library'
#    package        - build binary package
#
#    test           - run a minimal set of tests
#
#    setup_tests    - set up testsuite subprojects
#    prune_tests    - remove all testsuite subprojects
#
###
</pre>


    <a name="buildinformation"></a>
    <h3>Information about current configuration</h3>

    <p>
      A configuration run of <code>cmake</code> (or <code>ccmake</code>)
      writes a short summary of the current configuration into
      <code>CMAKE_BUILD_DIR/summary.log</code>:
<pre class="cmake">
###
#
#  deal.II configuration:
#        CMAKE_BUILD_TYPE:       DebugRelease
#        BUILD_SHARED_LIBS:      ON
#        CMAKE_INSTALL_PREFIX:   /tmp/deal.II/install
#        CMAKE_SOURCE_DIR:       /tmp/deal.II/deal.II (Version 8.1.pre)
#        CMAKE_BINARY_DIR:       /tmp/deal.II/build
#        CMAKE_CXX_COMPILER:     GNU 4.7.3 on platform Linux x86_64
#                                /usr/bin/c++
#
#  Configured Features (DEAL_II_ALLOW_BUNDLED = ON, DEAL_II_ALLOW_AUTODETECTION = ON):
#      ( DEAL_II_WITH_64BIT_INDICES = OFF )
#        DEAL_II_WITH_ARPACK set up with external dependencies
#        DEAL_II_WITH_BOOST set up with external dependencies
#        [...]
#
#  Component configuration:
#      ( DEAL_II_COMPONENT_DOCUMENTATION = OFF )
#        DEAL_II_COMPONENT_EXAMPLES
#
#  Detailed information (compiler flags, feature configuration) can be found in detailed.log
#
#  Run  $ make info  to print a help message with a list of top level targets
#
###
</pre>
      This summary is also printed at the end of the configuration phase.
      It tells you about build and install directory locations, feature
      configuration (whether a feature is enabled with external/internal
      dependencies, disabled or forced) and component configuration.
      A more detailed version can be found in
      <code>CMAKE_BUILD_DIR/detailed.log</code> that also includes detailed
      information about feature configuration, e.g.
<pre class="cmake">
#        DEAL_II_WITH_BOOST set up with external dependencies
#            BOOST_VERSION = 1.61.0
#            BOOST_DIR =
#            Boost_INCLUDE_DIRS = /usr/include
#            Boost_LIBRARIES = /usr/lib64/libboost_serialization-mt.so;/usr/lib64/libboost_system-mt.so;
# [...]
</pre>
      If this information is not sufficient, you might want to have a look
      at the following files in <code>CMAKE_BUILD_DIR</code>
      <ul>
        <li><code>CMakeCache.txt</code>: The file CMake stores its cached
        variables in. Do not change directly.
        <li><code>include/deal.II/base/config.h</code>: The generated
        config.h file
        <li><code>lib/cmake/deal.II/deal.IIConfig.cmake</code>: The project
        configuration file for external projects.
      </ul>
    </p>



    <a name="buildinsource"></a>
    <h3>Out-of-source versus in-source builds</h3>

    <p>
      A so called out-of-source build is a setup where the build directory
      (the directory containing intermediate and generated files) is
      different from the source directory (the directory containing the
      source code). With CMake an out-of-source build is set up by invoking
      <code>cmake</code> (or <code>ccmake</code>) from the designated build
      directory, so for example (a build directory under the source
      directory):
<pre class="cmake">
$ mkdir build
$ cd build
$ cmake ..
</pre>
      The big advantage is that source files and intermediate files are
      strictly separated (highly desired for version control) and that you
      can have multiple build directories (with different configuration) at
      the same time.
    </p>

    <p>
      <b>Note:</b> However, under rare occasions an in-source build might be
      useful or needed , so it is supported
<pre class="cmake">
$ cmake .
</pre>
      But we highly discourage it!
    </p>

    <a name="buildgenerator"></a>
    <h3>CMake Generators</h3>

    <p>
      Cmake is a <i>Makefile Generator</i>. This allows to switch the
      generator that is used to something different. If you for example want
      to automatically generate an Eclipse project of deal.II, you can run
<pre class="cmake">
$ cmake -G"Eclipse CDT4 - Unix Makefiles" [...]
</pre>
      and load up the build directory as a project directly into Eclipse.
      Have a look at
      the <a href="https://github.com/dealii/dealii/wiki/Eclipse">Wiki's
      Eclipse page</a> for more information.
    </p>

    <p>
      An interesting alternative to (GNU) Make might also be <a
      href="http://martine.github.io/ninja/">Ninja</a>. Configure via
<pre class="cmake">
$ cmake -GNinja [...]
</pre>
      and run <code>ninja</code> instead of <code>make</code>.
    </p>


    <a name="buildinstall"></a>
    <h3>Installation</h3>

    <p>
      It is not necessary to install the library in order to use deal.II.
      Invoking the <code>all</code> or <code>library</code> target will
      compile the library and set up all necessary configuration in the
      build directory so that external projects can directly use it.
      However, we strongly recommend to proceed in the way explained in the
      <a href="../readme.html" target="body">README</a> and install the
      library to a designated install directory (different from source and
      build directory).
    </p>

    <p>
      For installing the library it is necessary to set the CMake variable
      <code>CMAKE_INSTALL_PREFIX</code> to the designated install
      directory. You can do this by invoking <code>cmake</code> together
      with <code>-DCMAKE_INSTALL_PREFIX=&lt;...&gt;</code> or by invoking
      <code>ccmake</code>.
    </p>

    <p>
      <b>Note:</b> When you don't install deal.II to an install directory
      and use it directly from a build directory,
      both, the build <i>and</i> source directories have to be kept.
    </p>

    <p>
      <b>Note:</b> It is not necessary for the source, build and or install
      directory to be different. All combinations are supported.
    </p>


    <h4>Install a single component</h4>

    <p>
      If you want to only generate, compile and install a specific
      component (most notably the documentation) you can use one of the
      following top level targets:
      <pre class="cmake">
documentation  - builds and installs the 'documentation' component
examples       - builds and installs the 'examples' component
library        - builds and installs the 'library' component
</pre>


    <a name="configure"></a>
    <h2>Configuration options</h2>

    <p>
      The various configuration options of the
      <acronym>deal.II</acronym> library are organized in three
      categories: <a href="#configurefeature">feature</a>,
      <a href="#configurecomp">component</a>, and <a
      href="#configurebuild">build</a>/<a href="#configureinstall">install</a>
      configuration.
    </p>



    <a name="configurefeature"></a>
    <h3>Feature configuration</h3>

    <p>
      <acronym>deal.II</acronym> provides (optional) interfaces to quite a
      number of external libraries as well as multiple versions
      of <code>C++</code>. All of these options are represented
      by <code>cmake</code> variables that may be set to either <code>ON</code>
      or <code>OFF</code>.

      By default, <acronym>deal.II</acronym>'s <code>CMake</code> build scripts
      will attempt to find the newest <code>C++</code> version available by
      checking which language version flags work with the detected compiler. For
      example: if <code>CMake</code> detects <code>GCC 5.1</code> or <code>Clang
      3.6</code>, <acronym>deal.II</acronym> will be compiled
      in <code>C++14</code> mode unless <code>C++14</code> support is explicitly
      disabled. Another example: if <code>DEAL_II_WITH_CXX14=ON</code> is passed
      to <code>CMake</code>, then <acronym>deal.II</acronym> will check if the
      compiler supports enough of the <code>C++14</code> standard to enable
      the <code>C++14</code>-specific parts of the library. The configuration
      process will fail if a feature flag is passed in that cannot be supported.

      The remaining flags are set to <code>ON</code> if an external package is
      found or to <code>OFF</code> otherwise. By explicitly setting it to off
      either on the command line or using <code>ccmake</code>, you can
      prevent <acronym>deal.II</acronym> from using an external package, even if
      it is found.
    </p>

    <p>
      Specifically, the following variables exist (the list may grow
      over time, but names are standardized):
<pre class="cmake">
DEAL_II_WITH_64BIT_INDICES
DEAL_II_WITH_ADOLC
DEAL_II_WITH_ARPACK
DEAL_II_WITH_ASSIMP
DEAL_II_WITH_BOOST
DEAL_II_WITH_COMPLEX_VALUES
DEAL_II_WITH_CUDA
DEAL_II_WITH_CXX14
DEAL_II_WITH_CXX17
DEAL_II_WITH_GINKGO
DEAL_II_WITH_GMSH
DEAL_II_WITH_GSL
DEAL_II_WITH_HDF5
DEAL_II_WITH_LAPACK
DEAL_II_WITH_METIS
DEAL_II_WITH_MPI
DEAL_II_WITH_MUPARSER
DEAL_II_WITH_NANOFLANN
DEAL_II_WITH_NETCDF
DEAL_II_WITH_OPENCASCADE
DEAL_II_WITH_P4EST
DEAL_II_WITH_PETSC
DEAL_II_WITH_SCALAPACK
DEAL_II_WITH_SLEPC
DEAL_II_WITH_SUNDIALS
DEAL_II_WITH_SYMENGINE
DEAL_II_WITH_THREADS
DEAL_II_WITH_TRILINOS
DEAL_II_WITH_UMFPACK
DEAL_II_WITH_ZLIB
</pre>
      They all have standard meaning with the exception of
      two:
      <ul>
        <li> <code>DEAL_II_WITH_BOOST</code> is always <code>ON</code>
          since BOOST is a mandatory build time dependency.

        <li> <code>DEAL_II_WITH_THREADS</code> enables threading support
          with the help of the Threading Building Blocks (TBB) library.
      </ul>
    </p>

    <p>
      If enabled, each of the features above will usually add one or
      more dependencies to external or 'bundled' (i.e. bundled with
      <acronym>deal.II</acronym> and residing under <code>bundled/</code>)
      libraries.
    </p>

    <p>
      Additionally, the variable
<pre class="cmake">
DEAL_II_CXX_VERSION_FLAG
</pre>
      may be set to specify the <code>C++</code> language version flag passed to
      the compiler.
    </p>

    <p>
      There are some options to determine the behavior of the dependency
      resolution.
      <ul>
        <li>
          <p>
            <code>DEAL_II_ALLOW_BUNDLED</code>:
          </p>
          <p>
            If set to <code>ON</code> external libraries still have
            precedence. But if there is no external library the bundled
            library will be used.
            If set to <code>OFF</code> bundled libraries will not be
            used and the dependency resolution will fail if there is no
            external library.
          </p>
        <li>
          <p>
            <code>DEAL_II_FORCE_BUNDLED_(BOOST|MUPARSER|THREADS|UMFPACK)</code>:
          </p>
          <p>
            Forces the use of the bundled library regardless whether
            <code>DEAL_II_ALLOW_BUNDLED</code> is set to <code>OFF</code>
            or an external library is found.
          </p>
        <li>
          Thus, to ensure that no bundled library is used at all
          <code>DEAL_II_ALLOW_BUNDLED</code>, as well as every
          <code>DEAL_II_FORCE_BUNDLED_&lt;library&gt;</code>
          have to be set to <code>OFF</code>.  Conversely,
          <code>DEAL_II_FORCE_BUNDLED_&lt;library&gt;=ON</code>
          will not automatically enable the corresponding
          <code>DEAL_II_WITH_&lt;feature&gt;</code> toggle. This has to be
          set separately.
      </ul>
    </p>



    <a name="configureautoconf"></a>
    <h3> Autoconfiguration </h3>

    <p>
      As long as <code>DEAL_II_WITH_&lt;FEATURE&gt;</code> is
      not explicitly set to <code>ON</code> or <code>OFF</code>
      in the cache it will be automatically configured. If a toggle
      <code>DEAL_II_WITH_&lt;FEATURE&gt;</code> is defined it won't
      be altered.
      This means that the very first configuration run will set
      all available features to <code>ON</code> and the rest
      to <code>OFF</code>. In all subsequent configuration steps
      <code>DEAL_II_WITH_&lt;FEATURE&gt;</code> has to be changed by hand,
      see the previous section.
    </p>

    <p>
      This behavior can be controlled via several variables:
      <ul>
	<li>
          <code>DEAL_II_ALLOW_AUTODETECTION=OFF</code>: This will
          disable any autoconfiguration by setting undefined
          <code>DEAL_II_WITH_&lt;FEATURE&gt;</code> toggles to
          <code>OFF</code>.

	<li>
          <code>DEAL_II_FORCE_AUTODETECTION=ON</code>: This will
          force the reconfiguration of every feature by undefining
          <code>DEAL_II_WITH_&lt;FEATURE&gt;</code> prior to
          configuration, effectively overwriting <i>any</i> supplied or
          cached value.
      </ul>
    </p>


    <a name="configureext"></a>
    <h3> External library locations </h3>

    <p>
      External libraries will be searched depending on hints in the following
      order:
      <ol>
	<li>
	  <p>
            Paths specified via <code>CMAKE_PREFIX_PATH</code> take
            precedence, e.g. with
<pre class="cmake">
make -DCMAKE_PREFIX_PATH=~/workspace/local ../deal.II
</pre>
	    libraries from <code>~/workspace/local</code> will be
	    preferred for dependency resolution.
	  </p>

	<li>
	  <p>
	    Hints given by <code>&lt;library&gt;_DIR</code> via command
            line or environment for <i>some</i> libraries:
<pre class="cmake">
make -DP4EST_DIR=~/workspace/p4est-install/ ../deal.II
</pre>
	    or
<pre class="cmake">
export P4EST_DIR=~/workspace/p4est-install/
cmake ../deal.II
</pre>
            where <code>-D&lt;library&gt;_DIR</code> takes precedence
            over environment.
	  </p>

	  <p>
	    Currently, the following variables will be considered:
<pre class="cmake">
ARPACK_DIR,
BOOST_DIR,
HDF5_DIR,
LAPACK_DIR (and BLAS_DIR),
METIS_DIR,
MUPARSER_DIR,
P4EST_DIR (and SC_DIR),
PETSC_DIR and PETSC_ARCH (forming ${PETSC_DIR}/${PETSC_ARCH}),
SCALAPACK_DIR (and optionally BLACS_DIR)
SLEPC_DIR (forming ${SLEPC_DIR}/${PETSC_ARCH}),
TBB_DIR,
TRILINOS_DIR,
UMFPACK_DIR and SUITESPARSE_DIR (AMD_DIR, CHOLMOD_DIR, COLAMD_DIR, SUITESPARSECONFIG_DIR)
</pre>
	  </p>

	<li>
	  <p>
	    The default system locations for libraries and includes.
	  </p>
      </ol>
    </p>

    <p>
      Alternatively, cached variables set by the
      <code>Find&lt;Module&gt;</code> mechanism may be set,
      hinted or overwritten directly (variable names are highly
      dependent on the actual library). You can get a list via
<pre class="cmake">
make edit_cache
</pre>
      and entering advanced configuration mode by pressing [t].
      Variables that could not be determined are suffixed with
      <code>-NOTFOUND</code> and may be set by hand.
    </p>

    <h4>Library conflicts</h4>
    <p>Caveat: if you have a set of standard libraries in the default
    location, say <code>/usr/lib</code> and a set of
    private versions of the same libraries, for instance because you
    need different revisions sometimes, in your own library directory,
    you may receive an error message of the form:</p>

<pre class="cmake">
CMake Warning at source/CMakeLists.txt:65 (ADD_LIBRARY):
  Cannot generate a safe runtime search path for target deal_II.g because
  files in some directories may conflict with libraries in implicit
  directories:

    runtime library [libtbb.so.2] in /usr/lib may be hidden by files in:
      /my/private/lib

  Some of these libraries may not be found correctly.
</pre>

<p>This is not a problem of CMake or deal.II, but rather a general
  Linux problem. In order to fix this, you have two options:</p>
<ol>
<li>Choose all libraries either from your private directory or from
  the standard one.</li>
<li>Install all your private library versions in different directories.</li>
</ol>

    <a name="configureoverride"></a>
    <h3> Manual override </h3>
    <p><b>Warning:</b> Do not do this unless absolutely necessary!</p>
    <p>
      It is possible to override the CMake find mechanism for external
      libraries manually. This is useful if a non standard library (e.g.
      BLAS or LAPACK) should be used but cannot be found by the
      <code>FIND_PACKAGE(...)</code> mechanism.

      In this case you can set by hand:
<pre class="cmake">
cmake -D&lt;feature&gt;_FOUND=true \
      -D&lt;feature&gt;_LIBRARIES="library;and;complete;link;interface" \
    ( -D&lt;feature&gt;_INCLUDE_DIRS="semicolon;separated;list;of;include;dirs" \
      -D&lt;feature&gt;_LINKER_FLAGS="..." \
      -D&lt;feature&gt;_&lt;...depending on library...&gt; )
</pre>

      The first define ensures that <code>cmake</code> does not
      call the corresponding <code>Find&lt;lib&gt;.cmake</code> module.
      Therefore, all information that would be otherwise exported by the
      module must be specified by hand. (See the
      <a href="config.sample" target="_top">config.sample file</a> for a
      detailed list of valid variables per feature.)
    </p>
    <p>
      An example of use is to select BLAS and LAPACK manually from a PETSc
      configuration:
      (Here, these libraries have been compiled with the gfortran compiler
      and need its support library):
<pre class="cmake">
cmake -DLAPACK_FOUND=true \
      -DLAPACK_LIBRARIES="/tmp/petsc-3.3-p6/arch-linux2-c-debug/lib/libflapack.a;/tmp/petsc-3.3-p6/arch-linux2-c-debug/lib/libfblas.a" \
      -DLAPACK_LINKER_FLAGS="-lgfortran -lm"
</pre>

      You can set these values on the command line, with <code>ccmake</code>
      or by providing an initial cache file, see
      <a href="#advanced">advanced setup section</a>.
      Possible manual overrides are explained in detail in the
      in the <a href="config.sample" target="_top">config.sample file</a>.
    </p>


    <a name="configurecomp"></a>
    <h3> Component selection </h3>

    <p>
      The following options control which components of
      <acronym>deal.II</acronym> will be configured, built and installed:

      <ul>
	<li>
          <p>
            <code>DEAL_II_COMPONENT_DOCUMENTATION</code>
            (default <code>OFF</code>):
          </p>
          <p>
            Enable configuration, build and installation of the
            documentation including all of the tutorial programs and the
            doxygen-generated manual.  This adds a
            component <code>documentation</code> to the build system.
          </p>

	<li>
          <p>
            <code>DEAL_II_COMPONENT_EXAMPLES</code>
            (default <code>ON</code>):
          </p>
          <p>
            Enable configuration and installation of the example steps (but
            not generate the documentation for the tutorial steps).
            This adds a component <code>examples</code> to the build system.
          </p>
      </ul>
    </p>


    <a name="configurebuild"></a>
    <h3> Build configuration </h3>

    <p>
      The <code>cmake</code> variable <code>CMAKE_BUILD_TYPE</code>
      controls the type of build. We support <code>Debug</code>,
      <code>Release</code> and <code>DebugRelease</code> mode. Default
      is <code>DebugRelease</code>.
      <ul>
        <li>
          Passing <code>cmake</code> the
          flag <code>-DCMAKE_BUILD_TYPE=Debug</code> will produce makefiles
          that compile and install only the debug library
          <code>libdeal_II.g.so</code>.
        <li>
          Passing <code>cmake</code> the
          flag <code>-DCMAKE_BUILD_TYPE=Release</code> result in only
          compiling and installing the optimized library <code>libdeal_II.so</code>.
        <li>
          Passing <code>cmake</code> the
          flag <code>-DCMAKE_BUILD_TYPE=DebugRelease</code> will build and
          install both libraries.
      </ul>

      For more information, see the general discussion <a
        href="../readme.html#configuration">here</a>.
    </p>


    <p>
      The build can be further controlled by the following variables:
      <ul>
        <li>
          <code>DEAL_II_ALLOW_PLATFORM_INTROSPECTION</code>: If set
          (default), <acronym>deal.II</acronym> will perform platform
          introspection for the given CPU.

	<li>
          <code>BUILD_SHARED_LIBS</code>: If set (default),
          <acronym>deal.II</acronym> will be linked as a shared library

        <li>
        <code>DEAL_II_PREFER_STATIC_LIBS</code> (defaults to off): If set
        to true, static archives will be preferred over dynamic libraries when
        searching for features and corresponding link interface.

	<li>
          <code>DEAL_II_STATIC_EXECUTABLE</code> (defaults to off):
          If set to true, <acronym>deal.II</acronym> will be configured in
          a way to provide a link interface that is suitable for static
          linkage of executables. Enabling this option forces
          <code>BUILD_SHARED_LIBS=OFF</code> and
          <code>DEAL_II_PREFER_STATIC_LIBS=ON</code>.

	<li>
	  <code>CMAKE_INSTALL_RPATH_USE_LINK_PATH</code>: If set
	  (default), the <acronym>deal.II</acronym> library will be
	  installed with rpaths  set for all libraries outside of the
	  system search paths
      </ul>
    </p>


    <a name="compiler"></a>
    <h3> Selecting a compiler </h3>

    </p>
      Compilers can be switched either by command line or by setting
      <code>CMAKE_(C|CXX|Fortran)_COMPILER</code>:
<pre class="cmake">
CC=mpicc CXX=mpicxx FC=mpif90 cmake &lt;...&gt;

cmake -DCMAKE_C_COMPILER="mpicc" -DCMAKE_CXX_COMPILER="mpicxx" -DCMAKE_Fortran_COMPILER="mpif90" &lt;...&gt;
</pre>
      Please note that
      <ul>
        <li>
          The compiler <i>must</i> be specified at the very first
          invocation of <code>cmake</code>.
        <li>
          A working CXX compiler is needed. It is optional to provide a C
          or Fortran compiler.
      </ul>
    </p>

    <p>
      deal.II will configure sensible default <code>CXXFLAGS</code> and
      <code>LDFLAGS</code> depending on platform, compiler and build
      target. There are two options to override this behaviour:

      <ol>
	<li>
	  Override the default configuration by setting the following
	  cached variables:
<pre class="cmake">
DEAL_II_CXX_FLAGS         - used during all builds
DEAL_II_CXX_FLAGS_DEBUG   - additional flags for the debug library
DEAL_II_CXX_FLAGS_RELEASE - additional flags for the release library

DEAL_II_LINKER_FLAGS         - used during all builds
DEAL_II_LINKER_FLAGS_DEBUG   - additional flags for the debug library
DEAL_II_LINKER_FLAGS_RELEASE - additional flags for the release library
</pre>

	  The content of the cached variables will be preserved
	  and added <i>to the end</i> of the default compiler flags,
	  hence providing the possibility for overriding a flag. E.g.:
	  <code>-Wsign-compare</code>, set by the build system, can be
	  overwritten by specifying:
<pre class="cmake">
cmake -DDEAL_II_CXX_FLAGS="-Wno-sign-compare" &lt;...&gt;
</pre>

        <li>
          Set the corresponding environment variables: <code>CFLAGS</code>,
          <code>CXXFLAGS</code>, or <code>LDFLAGS</code> environment. These
          variables will also be appended after the default compiler flags
          (but before the corresponding cached variables).

	<li>
	  Disable the configuration completely by adding the flag
	  <code>-D DEAL_II_SETUP_DEFAULT_COMPILER_FLAGS=OFF</code>.
	  Beware of the fact that certain features
	  may still pull in necessary compiler flags.

        <li>
          You can setup additional debug compiler flags to provide test
          coverage information by adding the flag
          <code>-D DEAL_II_SETUP_COVERAGE=ON</code>.
      </ol>
    </p>


    <a name="configureinstall"></a>
    <h3> Installation </h3>

    <p>
      the location, where the <acronym>deal.II</acronym> library will be
      installed when invoking <code>make install</code> to is set with the
      help of
<pre class="cmake">
CMAKE_INSTALL_PREFIX
</pre>

      The default directory structure is:
<pre class="cmake">
${CMAKE_INSTALL_PREFIX}/
    bin
    include
    lib${LIB_SUFFIX}
    lib${LIB_SUFFIX}/cmake/deal.II
    share/deal.II/
    ./
    doc
    examples
</pre>
      </ul>
    </p>

    <p>
      The default directory structure can be changed by setting the
      following variables:
<pre class="cmake">
DEAL_II_EXECUTABLE_RELDIR       default: bin
DEAL_II_INCLUDE_RELDIR          default: include
DEAL_II_LIBRARY_RELDIR          default: lib${LIB_SUFFIX}
DEAL_II_PROJECT_CONFIG_RELDIR   default: lib${LIB_SUFFIX}/cmake/deal.II
DEAL_II_SHARE_RELDIR            default: share/deal.II/
DEAL_II_DOCREADME_RELDIR        default: ./
DEAL_II_DOCHTML_RELDIR          default: doc
DEAL_II_EXAMPLES_RELDIR         default: examples
</pre>
    </p>

    <a name="advanced"></a>
    <h2>Initial cache file and advanced options</h2>

    <p>
      A sample configuration file for preloading the CMake cache with
<pre class="cmake">
$ cmake -C config.sample <...>
</pre>
      can be found <a href="config.sample" target="_top">here</a>.
      This sample configuration covers all options mentioned in this
      documentation as well as some advanced aspects in feature
      configuration.
    </p>

    <a name="compiling"></a>
    <h2> Compiling only certain parts </h2>
    <p>

    <p>
      While developing the library itself, it is often desirable
      to only compile certain parts. The build system generated by
      <code>cmake</code> allows to build specific, selected targets.
      A common scenario is that you only want to build debug or optimized
      libraries. This can be achieved using the following commands in
      the build directory:
<pre class="cmake">
make  deal_II.g        # only debug library
make  deal_II          # only release (optimized) library
make  all              # both

make  obj_grid.release # all objects in ./source/grid in release configuration
</pre>
    </p>

    <p>
      For a complete list of possible targets that allow even
      finer-grained control, do
<pre class="cmake">
make  help
</pre>
    </p>

    <p>
      It is frequently useful to be able to see what a particular
      command does. In that case, use the following:
<pre class="cmake">
make  deal_II.g VERBOSE=ON
</pre>
      This will show, for every command executed, the exact command
      line with which it was invoked, including compiler arguments,
      etc. Every command <code>cmake</code> executes starts with
      a <code>cd</code> command to change the current directory
      appropriately so that the command line can be copied and executed
      from anywhere within the build directory.
    </p>

    <p>
      <b>Note:</b> Just because you can call <code>make deal_II.g</code> to
      only compile the debug version does not mean that a
      subsequent <code>make install</code> will only install the debug
      library. Rather, <code>make install</code> will still want to have both
      libraries up to date and will therefore invoke <code>make all</code>
      automatically. To restrict builds in such a way that only one library
      will be installed, see <a href="#configurebuild">configuration</a>
      and <a href="#buildinstall">installation</a> sections.
    </p>

    <hr />
    <div class="right">
      <a href="http://validator.w3.org/check?uri=referer" target="_top">
        <img style="border:0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
      <a href="http://jigsaw.w3.org/css-validator/check/referer" target="_top">
        <img style="border:0;width:88px;height:31px" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
    </div>

  </body>
</html>
